---
title: 数据验证
icon: Grid2x2Check
---

<MetaData
  lang="zh-CN"
  meta={{
    preset: [{
      client: '@univerjs/preset-sheets-data-validation',
      locale: '@univerjs/preset-sheets-data-validation/locales/zh-CN',
      style: '@univerjs/preset-sheets-data-validation/lib/index.css',
    }],
    plugins: [{
      client: '@univerjs/data-validation',
    }, {
      client: '@univerjs/sheets-data-validation',
      facade: '@univerjs/sheets-data-validation/facade',
    }, {
      client: '@univerjs/sheets-data-validation-ui',
      locale: '@univerjs/sheets-data-validation-ui/locale/zh-CN',
      style: '@univerjs/sheets-data-validation-ui/lib/index.css',
    }],
    server: '否',
  }}
/>

数据验证是一种在单元格中设置规则的功能，以确保输入的数据符合特定要求。它可以帮助用户避免输入错误，提高数据的准确性和一致性。

目前支持以下数据验证类型：
- 数字
- 整数
- 文本长度
- 日期
- 复选框
- 下拉列表(单选/多选)
- 自定义公式

## 预设模式

### 安装

```package-install
npm install @univerjs/preset-sheets-data-validation
```

### 使用

```typescript
import { UniverSheetsCorePreset } from '@univerjs/preset-sheets-core'
import UniverPresetSheetsCoreZhCN from '@univerjs/preset-sheets-core/locales/zh-CN'
import { UniverSheetsDataValidationPreset } from '@univerjs/preset-sheets-data-validation' // [!code ++]
import UniverPresetSheetsDataValidationZhCN from '@univerjs/preset-sheets-data-validation/locales/zh-CN' // [!code ++]
import { createUniver, LocaleType, mergeLocales } from '@univerjs/presets'

import '@univerjs/preset-sheets-core/lib/index.css'
import '@univerjs/preset-sheets-data-validation/lib/index.css' // [!code ++]

const { univerAPI } = createUniver({
  locale: LocaleType.ZH_CN,
  locales: {
    [LocaleType.ZH_CN]: mergeLocales(
      UniverPresetSheetsCoreZhCN,
      UniverPresetSheetsDataValidationZhCN, // [!code ++]
    ),
  },
  presets: [
    UniverSheetsCorePreset(),
    UniverSheetsDataValidationPreset(), // [!code ++]
  ],
})
```

### 预设与配置

```typescript
UniverSheetsDataValidationPreset({
  // 是否在下拉菜单中显示编辑按钮
  showEditOnDropdown: true,
})
```

完整的配置项参考 [`IUniverSheetsDataValidationPresetConfig`](https://github.com/dream-num/univer-presets/blob/dev/packages/preset-sheets-data-validation/src/umd.ts#L13)。

## 插件模式

### 安装

```package-install
npm install @univerjs/data-validation @univerjs/sheets-data-validation @univerjs/sheets-data-validation-ui
```

### 使用

```typescript
import { LocaleType, mergeLocales, Univer } from '@univerjs/core'
import { UniverDataValidationPlugin } from '@univerjs/data-validation' // [!code ++]
import { UniverSheetsDataValidationPlugin } from '@univerjs/sheets-data-validation' // [!code ++]
import { UniverSheetsDataValidationUIPlugin } from '@univerjs/sheets-data-validation-ui' // [!code ++]
import SheetsDataValidationZhCN from '@univerjs/sheets-data-validation-ui/locale/zh-CN' // [!code ++]

import '@univerjs/sheets-data-validation-ui/lib/index.css' // [!code ++]

import '@univerjs/sheets-data-validation/facade' // [!code ++]

const univer = new Univer({
  locale: LocaleType.ZH_CN,
  locales: {
    [LocaleType.ZH_CN]: mergeLocales(
      SheetsDataValidationZhCN, // [!code ++]
    ),
  },
})

univer.registerPlugin(UniverDataValidationPlugin) // [!code ++]
univer.registerPlugin(UniverSheetsDataValidationPlugin) // [!code ++]
univer.registerPlugin(UniverSheetsDataValidationUIPlugin) // [!code ++]
```

### 插件与配置

```typescript
univer.registerPlugin(UniverSheetsDataValidationUIPlugin, {
  // 是否在下拉菜单中显示编辑按钮
  showEditOnDropdown: true,
})
```

完整的配置项参考 [`IUniverSheetsDataValidationUIConfig`](https://github.com/dream-num/univer/blob/dev/packages/sheets-data-validation-ui/src/controllers/config.schema.ts#L23)。

## Facade API

完整 Facade API 类型定义，请查看 [FacadeAPI](https://reference.univer.ai/zh-CN)

### 添加一个数据验证规则

[`univerAPI.newDataValidation()`](https://reference.univer.ai/zh-CN/classes/FUniver#newdatavalidation) 可以创建一个新的数据验证构建器，返回一个 `FDataValidationBuilder` 实例，可以通过链式调用生成数据验证规则。

以下是 [`FDataValidationBuilder`](https://reference.univer.ai/zh-CN/classes/FDataValidationBuilder) 上的一些成员方法：

| 方法 | 描述 |
| ---- | ---- |
| build | 构建数据验证规则 |
| requireCheckbox | 设置数据验证规则，要求输入为布尔值；该值将呈现为复选框 |
| requireDateAfter | 将数据验证类型设置为 DATE，并配置验证规则为在特定日期之后 |
| requireDateBefore | 将数据验证类型设置为 DATE，并配置验证规则为在特定日期之前 |
| requireDateBetween | 将数据验证类型设置为 DATE，并配置验证规则为在特定日期范围内 |
| requireDateEqualTo | 将数据验证类型设置为 DATE，并配置验证规则为等于特定日期 |
| requireDateNotBetween | 将数据验证类型设置为 DATE，并配置验证规则为不在特定日期范围内 |
| requireDateOnOrAfter | 将数据验证类型设置为 DATE，并将验证规则配置为特定日期或之后 |
| requireDateOnOrBefore | 将数据验证类型设置为 DATE，并将验证规则配置为特定日期或之前 |
| requireFormulaSatisfied | 设置数据验证规则要求给定公式求值为 `true` |
| requireNumberBetween | 设置数据验证规则要求数字在两个指定数字之间，或者是其中之一 |
| requireNumberEqualTo | 设置数据验证规则要求数字等于给定值 |
| requireNumberGreaterThan | 设置数据验证规则要求数字大于给定值 |
| requireNumberGreaterThanOrEqualTo | 设置数据验证规则要求数字大于或等于给定值 |
| requireNumberLessThan | 设置数据验证规则要求数字小于给定值 |
| requireNumberLessThanOrEqualTo | 设置数据验证规则要求数字小于或等于给定值 |
| requireNumberNotBetween | 设置数据验证规则要求数字不在两个指定数字之间，也不是其中之一 |
| requireNumberNotEqualTo | 设置数据验证规则要求数字不等于给定值 |
| requireValueInList | 设置数据验证规则，要求用户从特定值列表中输入一个值。 |
| requireValueInRange | 设置数据验证规则，要求用户输入特定范围内的值 |
| setOptions | 设置数据验证规则的选项 |

```typescript
const fWorkbook = univerAPI.getActiveWorkbook()
const fWorksheet = fWorkbook.getActiveSheet()

// 创建一个新的数据验证规则，要求 A1:B10 范围内的数字在 1 到 10 之间
const fRange = fWorksheet.getRange('A1:B10')
const rule = univerAPI.newDataValidation()
  .requireNumberBetween(1, 10)
  .setOptions({
    allowBlank: true,
    showErrorMessage: true,
    error: 'Please enter a number between 1 and 10',
  })
  .build()
fRange.setDataValidation(rule)
```

### 清除 Range 的数据验证规则

```typescript
const fWorkbook = univerAPI.getActiveWorkbook()
const fWorksheet = fWorkbook.getActiveSheet()

// 清除 A1:B10 范围内的数据验证规则
const fRange = fWorksheet.getRange('A1:B10')
fRange.setDataValidation(null)
```

### 获取 Range/Worksheet 的数据验证规则

返回的数据验证规则对象是一个 `FDataValidation` 实例，可以通过该实例获取验证规则的条件、选项等。

以下是 [`FDataValidation`](https://reference.univer.ai/zh-CN/classes/FDataValidation) 上的一些成员方法：

| 方法 | 描述 |
| ---- | ---- |
| getCriteriaType | 获取数据验证规则的类型 |
| getCriteriaValues | 获取数据验证规则的条件值 |
| getHelpText | 获取帮助文本信息，用于为用户提供指导和支持 |
| getRanges | 获取数据验证规则的应用范围 |
| setCriteria | 设置数据验证规则的条件值 |
| setOptions | 设置数据验证规则的选项 |
| setRanges | 设置数据验证规则的应用范围 |
| delete | 从工作表中删除数据验证规则 |

```typescript
const fWorkbook = univerAPI.getActiveWorkbook()
const fWorksheet = fWorkbook.getActiveSheet()

// 获取当前工作表的所有数据验证规则
const rulesOfSheet = fWorksheet.getDataValidations()

const fRange = fWorksheet.getRange('A1:B10')

// 获取当前范围的第一个数据验证规则
const ruleOfRange = fRange.getDataValidation()
ruleOfRange?.getCriteriaValues()

// 获取当前范围的所有数据验证规则
const rulesOfRange = fRange.getDataValidations()
```

### 更新/删除数据验证

```typescript
const fWorkbook = univerAPI.getActiveWorkbook()
const fWorksheet = fWorkbook.getActiveSheet()

// 创建一个新的数据验证规则，要求 A1:B10 范围内的数字等于 20
const fRange = fWorksheet.getRange('A1:B10')
const rule = univerAPI.newDataValidation()
  .requireNumberEqualTo(20)
  .build()
fRange.setDataValidation(rule)

const newRuleRange = fWorksheet.getRange('C1:D10')

// 3 秒后更新规则
setTimeout(() => {
  fRange.getDataValidation()
    // 更改新的范围 C1:D10
    .setRanges([newRuleRange])
    // 更改新的条件，要求数字在 1 到 10 之间
    .setCriteria(
      univerAPI.Enum.DataValidationType.DECIMAL,
      [univerAPI.Enum.DataValidationOperator.BETWEEN, '1', '10'],
    )
    // 更改验证选项，当输入不符合条件时停止输入并显示错误消息
    .setOptions({
      allowBlank: true,
      showErrorMessage: true,
      error: 'Please enter a valid value',
      errorStyle: univerAPI.Enum.DataValidationErrorStyle.STOP,
    })
}, 3000)

// 6 秒后删除该规则
setTimeout(() => {
  newRuleRange.getDataValidation().delete()
}, 6000)
```

### 查询校验状态

```typescript
const fWorkbook = univerAPI.getActiveWorkbook()
const fWorksheet = fWorkbook.getActiveSheet()

// 获取当前工作簿的数据验证校验状态
fWorkbook.getValidatorStatus().then((status) => {
})

// 获取当前工作表的数据验证校验状态
fWorksheet.getValidatorStatusAsync().then((status) => {
})

// 获取当前范围的数据验证校验状态
const fRange = fWorksheet.getRange('A1:B10')
fRange.getValidatorStatus().then((status) => {
})
```

### 事件监听

完整事件类型定义，请查看 [Events](https://reference.univer.ai/zh-CN/classes/FEventName)。

数据验证模块提供了一系列事件用于监听验证规则的添加、更新、删除和验证状态变更。所有事件都可以通过 `univerAPI.addEvent()` 进行监听。

#### 验证规则变更事件

`univerAPI.Event.SheetDataValidationChanged`: 验证规则变更后触发

```typescript
const disposable = univerAPI.addEvent(univerAPI.Event.SheetDataValidationChanged, (params) => {
  const { origin, worksheet, workbook, changeType, oldRule, rule } = params
})

// 移除事件监听器，使用 `disposable.dispose()`
```

`univerAPI.Event.BeforeSheetDataValidationAdd`: 添加验证规则前触发

```typescript
const disposable = univerAPI.addEvent(univerAPI.Event.BeforeSheetDataValidationAdd, (params) => {
  const { worksheet, workbook, rule } = params

  // 取消添加验证规则操作
  params.cancel = true
})

// 移除事件监听器，使用 `disposable.dispose()`
```

`univerAPI.Event.BeforeSheetDataValidationDelete`: 删除验证规则前触发

```typescript
const disposable = univerAPI.addEvent(univerAPI.Event.BeforeSheetDataValidationDelete, (params) => {
  const { worksheet, workbook, ruleId, rule } = params

  // 取消删除验证规则操作
  params.cancel = true
})

// 移除事件监听器，使用 `disposable.dispose()`
```

`univerAPI.Event.BeforeSheetDataValidationDeleteAll`: 删除所有验证规则前触发

```typescript
const disposable = univerAPI.addEvent(univerAPI.Event.BeforeSheetDataValidationDeleteAll, (params) => {
  const { worksheet, workbook, rules } = params

  // 取消删除所有验证规则操作
  params.cancel = true
})

// 移除事件监听器，使用 `disposable.dispose()`
```

#### 验证规则更新事件

`univerAPI.Event.BeforeSheetDataValidationCriteriaUpdate`: 更新验证规则条件前触发

```typescript
const disposable = univerAPI.addEvent(univerAPI.Event.BeforeSheetDataValidationCriteriaUpdate, (params) => {
  const { worksheet, workbook, ruleId, rule, newCriteria } = params

  // 取消更新验证规则条件操作
  params.cancel = true
})

// 移除事件监听器，使用 `disposable.dispose()`
```

`univerAPI.Event.BeforeSheetDataValidationRangeUpdate`: 更新验证规则范围前触发

```typescript
const disposable = univerAPI.addEvent(univerAPI.Event.BeforeSheetDataValidationRangeUpdate, (params) => {
  const { worksheet, workbook, ruleId, rule, newRanges } = params

  // 取消更新验证规则范围操作
  params.cancel = true
})

// 移除事件监听器，使用 `disposable.dispose()`
```

`univerAPI.Event.BeforeSheetDataValidationOptionsUpdate`: 更新验证规则选项前触发

```typescript
const disposable = univerAPI.addEvent(univerAPI.Event.BeforeSheetDataValidationOptionsUpdate, (params) => {
  const { worksheet, workbook, ruleId, rule, newOptions } = params

  // 取消更新验证规则选项操作
  params.cancel = true
})

// 移除事件监听器，使用 `disposable.dispose()`
```

#### 验证状态事件

`univerAPI.Event.SheetDataValidatorStatusChanged`: 单元格验证状态变更时触发

```typescript
const disposable = univerAPI.addEvent(univerAPI.Event.SheetDataValidatorStatusChanged, (params) => {
  const { worksheet, workbook, row, column, status, rule } = params
})

// 移除事件监听器，使用 `disposable.dispose()`
```

每个事件都包含以下通用参数：
- `workbook`: 当前工作簿实例
- `worksheet`: 当前工作表实例

特殊参数：
- `rule`: 相关的验证规则对象
- `ruleId`: 验证规则的唯一标识符
- `status`: 验证状态（仅在 `SheetDataValidatorStatusChanged` 事件中）
- `newCriteria`: 新的验证条件（仅在 `BeforeSheetDataValidationCriteriaUpdate` 事件中）
- `newRanges`: 新的验证范围（仅在 `BeforeSheetDataValidationRangeUpdate` 事件中）
- `newOptions`: 新的验证选项（仅在 `BeforeSheetDataValidationOptionsUpdate` 事件中）

所有 `Before` 前缀的事件回调函数都可以使用 `params.cancel = true` 来阻止对应的操作。

### 变更列表型验证的渲染模式

```typescript
dataValidation.setOptions({
  // support TEXT, ARROW, CUSTOM
  // default is `CUSTOM`
  renderMode: univerAPI.Enum.DataValidationRenderMode.TEXT,
})
```
